[SYNPY-1673] Add JSONSchema documentation, deprecate old classes #1262
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
* Update jsonschema tutorial * Update script * update script locations * Add a line
jaymedina
reviewed
Oct 23, 2025
|
There are broken reference links in the appendix: |
jaymedina
reviewed
Oct 23, 2025
| * You have a working [installation](../installation.md) of the Synapse Python Client. | ||
| * Make sure that you have completed the [Project](./project.md) tutorial, which covers creating and managing projects in Synapse. This is a prerequisite because you need a project to organize and store the folder used in this tutorial. | ||
| * You are familiar with Synapse concepts: [Project](./project.md), [Folder](./folder.md), [File](./file.md). | ||
| * You are familiar with [adding annotations](./annotation.md) to synapse entity. |
There was a problem hiding this comment.
nit: Would also add that familiarity with SchemaOrganization is also necessary
linglp
reviewed
Oct 27, 2025
| try: | ||
| schema.get() | ||
| except Exception as e: | ||
| schema.store(schema_body=schema_body, version=VERSION) |
There was a problem hiding this comment.
When I ran the tutorial, I got an error:
Traceback (most recent call last):
File "/Users/lpeng/code/synapsePythonClient/docs/tutorials/python/tutorial_scripts/json_schema.py", line 91, in <module>
raise e
File "/Users/lpeng/code/synapsePythonClient/docs/tutorials/python/tutorial_scripts/json_schema.py", line 84, in <module>
schema.store(schema_body=updated_schema, version=VERSION)
File "/Users/lpeng/code/synapsePythonClient/synapseclient/core/async_utils.py", line 69, in f
return self.fn(obj, *args, **kwds)
^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/Users/lpeng/code/synapsePythonClient/synapseclient/core/async_utils.py", line 188, in newmethod
return asyncio.run(wrapper(*args, **kwargs))
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/Users/lpeng/.pyenv/versions/3.12.6/lib/python3.12/asyncio/runners.py", line 194, in run
return runner.run(main)
^^^^^^^^^^^^^^^^
File "/Users/lpeng/.pyenv/versions/3.12.6/lib/python3.12/asyncio/runners.py", line 118, in run
return self._loop.run_until_complete(task)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/Users/lpeng/.pyenv/versions/3.12.6/lib/python3.12/asyncio/base_events.py", line 687, in run_until_complete
return future.result()
^^^^^^^^^^^^^^^
File "/Users/lpeng/code/synapsePythonClient/synapseclient/core/async_utils.py", line 175, in wrapper
return await getattr(self, async_method_name)(*args, **kwargs)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/Users/lpeng/code/synapsePythonClient/synapseclient/models/schema_organization.py", line 947, in store_async
completed_request: CreateSchemaRequest = await request.send_job_and_wait_async(
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/Users/lpeng/code/synapsePythonClient/synapseclient/models/mixins/asynchronous_job.py", line 123, in send_job_and_wait_async
results = await send_job_and_wait_async(
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/Users/lpeng/code/synapsePythonClient/synapseclient/models/mixins/asynchronous_job.py", line 338, in send_job_and_wait_async
**await get_job_async(
^^^^^^^^^^^^^^^^^^^^
File "/Users/lpeng/code/synapsePythonClient/synapseclient/models/mixins/asynchronous_job.py", line 463, in get_job_async
result = await client.rest_get_async(
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/Users/lpeng/code/synapsePythonClient/synapseclient/client.py", line 8990, in rest_get_async
response = await self._rest_call_async(
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/Users/lpeng/code/synapsePythonClient/synapseclient/client.py", line 8960, in _rest_call_async
self._handle_httpx_synapse_http_error(response)
File "/Users/lpeng/code/synapsePythonClient/synapseclient/client.py", line 8645, in _handle_httpx_synapse_http_error
exceptions._raise_for_status_httpx(
File "/Users/lpeng/code/synapsePythonClient/synapseclient/core/exceptions.py", line 296, in _raise_for_status_httpx
raise SynapseHTTPError(message, response=response)
synapseclient.core.exceptions.SynapseHTTPError: 403 Client Error: You do not have CREATE permission for ORGANIZATION : 1255
/schema/type/create/async: 0%| | 0.00/1.00 [00:01<?, ?it/s]
I think maybe it makes sense to have the schema already stored so that users can just get the schema?
There was a problem hiding this comment.
I'll defer to the team, but throughout these tutorials, these resources will have already been created and it's up to the user to update the names as they run the script so there's no name clashes.
Although, I'm unsure how clear we explicitly make that in our tutorials.
linglp
reviewed
Oct 27, 2025
| # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1583 | ||
| @deprecated( | ||
| version="4.11.0", | ||
| reason="To be removed in 5.0.0.", |
There was a problem hiding this comment.
I checked other deprecation messages, and it seems that they usually mention which new methods should be used instead. It might be helpful to add that here as well.
There was a problem hiding this comment.
The only thing that this was supporting was the jsonschema services. So we could point to the jsonschema services in general, or just leave it as is.
thomasyu888
reviewed
Oct 27, 2025
|
|
||
| # 2. Take a look at the constants and structure of the JSON schema | ||
| ORG_NAME = "myUniqueAlzheimersResearchOrgTutorial" | ||
| ORG_NAME = "myUniqueAlzheimersResearchOrgTutorialTest" |
There was a problem hiding this comment.
Suggested change
| ORG_NAME = "myUniqueAlzheimersResearchOrgTutorialTest" | |
| ORG_NAME = "myUniqueAlzheimersResearchOrgTutorial" |
thomasyu888
reviewed
Oct 27, 2025
|
|
||
| ```python | ||
| {!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=1-19} | ||
| {!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=1-10} |
There was a problem hiding this comment.
@andrewelamb please be sure to triple check these line references if there were changes made to that python script.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Problem:
The new JSONSchema classes need documentation.
The old JSONSchema classes need to be deprecated.
While writing the tutorial a bug was found:
JSONSchema.store-asyncwas overwriting itsidattribute with theidfield from the CreateSchemaResponse . These are not the same thing.JSONSchema.idis an integer identifier created by synapse in string form (ie.1880). The id from CreateSchemaResponse is a url.Solution:
Documentation files added for new JSONSchema classes.
Old JSONSchema classes are deprecated. For these, I just deprecated the classes. The old file states
This is a beta implementation and is subject to change. Use at your own risk.so i didn't include examples of how to use the new classes here. I can add these if needed.Tutorials added in this PR
The bug was fixed in
JSONSchema.store-asyncby not updating theidattribute.